home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Pdev_Open.man < prev    next >
Encoding:
Text File  |  1989-01-19  |  10.9 KB  |  267 lines
  1.  
  2.  
  3.  
  4. Pdev_Open          UNKNOWN SECTION (libcalls)           Pdev_Open
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Pdev_Open - open  pseudo-device  and  install  service  pro-
  12.      cedures for it.
  13.  
  14. SSYYNNOOPPSSIISS
  15.      ##iinncclluuddee <<ppddeevv..hh>>
  16.  
  17.      ClientData PPddeevv__OOppeenn(_n_a_m_e, _r_e_a_l_N_a_m_e_P_t_r, _s_e_r_v_i_c_e)
  18.  
  19. AARRGGUUMMEENNTTSS
  20.      char   *_n_a_m_e         (in)      Name  of  file  to  use   for
  21.                                     pseudo-device.
  22.  
  23.      char   **_r_e_a_l_N_a_m_e_P_t_r (out)     Where  to  store  pointer  to
  24.                                     actual   pseudo-device   file
  25.                                     name, or NULL if _n_a_m_e  is  to
  26.                                     be   the   complete  name  of
  27.                                     pseudo-device file.
  28.  
  29.      IntProc   *_s_e_r_v_i_c_e             Array  of  service  call-back
  30.                                     procedures.
  31.  
  32. _________________________________________________________________
  33.  
  34. DDEESSCCRRIIPPTTIIOONN
  35.      PPddeevv__OOppeenn creates a pseudo-device and installs a set of ser-
  36.      vice  procedures  for it.  The service procedures are called
  37.      when client processes open and use the  pseudo-device.   The
  38.      callbacks  are  given  as  an array of procedures (IInnttPPrroocc).
  39.      Any of the array elements can be NULL to indicate  that  the
  40.      operation  should be handled by a default handler.  The sseerr--
  41.      vviiccee parameter itself can also be NULL to  indicate  default
  42.      handling  for  all  operations.   This is only useful during
  43.      initial test.  If a client makes an operation for  which  no
  44.      service  procedure  is  provided it is simply a no-op; it is
  45.      not an error.  The global variable ppddeevvTTrraaccee can be  set  to
  46.      generate  printfs  when  each  service procedure (default or
  47.      user-supplied) is invoked.  The details of the service  pro-
  48.      cedures  are described below, after a description of how the
  49.      pseudo-device's name is chosen by PPddeevv__OOppeenn.
  50.  
  51.      There are two ways that PPddeevv__OOppeenn can pick the name  of  the
  52.      file  to use for the pseudo-device.  If _r_e_a_l_N_a_m_e_P_t_r is NULL,
  53.      then PPddeevv__OOppeenn uses _n_a_m_e as the name.  If _r_e_a_l_N_a_m_e_P_t_r  isn't
  54.      NULL,  then  PPddeevv__OOppeenn will generate a file name of the form
  55.      _h_o_s_t_D_i_r//_n_a_m_e_X_X, where _h_o_s_t_D_i_r is  the  name  of  a  standard
  56.      host-specific  directory, _n_a_m_e is the parameter to this pro-
  57.      cedure, and _X_X is a decimal number generated  by  PPddeevv__OOppeenn.
  58.      PPddeevv__OOppeenn  tries  numbers  up from 1 until it finds one that
  59.      works.  The name of the  successful  pseudo-device  file  is
  60.      returned  by  storing  a pointer to it at *_r_e_a_l_N_a_m_e_P_t_r;  the
  61.      storage for the name is dynamically  allocated  with  mmaalllloocc
  62.  
  63.  
  64.  
  65. Sprite v.1.0       Printed:  January 19, 1989                   1
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72. Pdev_Open          UNKNOWN SECTION (libcalls)           Pdev_Open
  73.  
  74.  
  75.  
  76.      and must eventually be freed by the caller.
  77.  
  78.      The return value of PPddeevv__OOppeenn is a  token  for  the  pseudo-
  79.      device,  which  must  be  used  in  calls  to PPddeevv__CClloossee and
  80.      PPddeevv__RReeaaddyy.  If a pseudo-device  couldn't  be  opened,  then
  81.      NULL   is  returned  and  ppddeevv__EErrrroorrMMssgg  contains  a  string
  82.      describing the problem.
  83.  
  84.      The Pdev package uses the facilities of FFss__DDiissppaattcchh in order
  85.      to  keep  track  of  the streams associated with the pseudo-
  86.      device and ensure  that  Pdev  is  notified  whenever  those
  87.      streams  become  readable.   In  order to use Pdev, you must
  88.      also use FFss__DDiissppaattcchh.
  89.  
  90.      The service procedures in the service array  are indexed  by
  91.      the pseudo-device operation type.  Thus
  92.  
  93.           bzero(service, PDEV_NUM_OPS * sizeof(IntProc));
  94.           service[PDEV_OPEN] = MyOpenProc;
  95.           service[PDEV_READ] = MyReadProc;
  96.      is a valid initialization for the service array that defines
  97.      open  and read callbacks, and leaves the other pseudo-device
  98.      operations as no-ops.
  99.  
  100.      The return value of a service procedure will be  the  return
  101.      value  of  the corresponding system call by the client, with
  102.      the exception of FS_WOULD_BLOCK as described below.
  103.  
  104. PPDDEEVV__OOPPEENN
  105.           ReturnStatus
  106.           OpenProc(token, flags, pid, hostID, uid, privatePtr, selectBitsPtr)
  107.               ClientData token;    /* Token to identify stream to pseudo-device. */
  108.                          /* Pass this token to Pdev_Ready */
  109.               int flags;      /* Flags to the open system call */
  110.               int pid;        /* ID of process opening the pseudo-device */
  111.               int hostID;          /* Host where that process is executing */
  112.               int uid;        /* User ID of that process */
  113.               ClientData *privatePtr;   /* Settable by openProc for its own use */
  114.               int *selectBitsPtr;  /* Return - the initial select state of the process */
  115.                          /* A combination of FS_READABLE|FS_WRITABLE|FS_EXCEPTION */
  116.  
  117.      The open service procedure gives  the  server  a  chance  to
  118.      refuse or accept the open by the client process.  The return
  119.      value of the open procedure is passed back as the return  of
  120.      the client's open system call.  The private data pointer can
  121.      be set by the open  service  procedure  to  reference  state
  122.      specific to its own needs.  This pointer is passed back into
  123.      the other service procedures.  There is also a token  passed
  124.      into  the  openProc  which  distinguishes  the stream to the
  125.      pseudo-device.  This token is to be used with the Pdev_Ready
  126.      procedure  that indicates the stream to the pseudo-device is
  127.      ready for I/O.
  128.  
  129.  
  130.  
  131. Sprite v.1.0       Printed:  January 19, 1989                   2
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138. Pdev_Open          UNKNOWN SECTION (libcalls)           Pdev_Open
  139.  
  140.  
  141.  
  142.      The selectBits are used in the  kernel's  implementation  of
  143.      sseelleecctt(())  for  pseudo-devices.   They should be a bitwise or
  144.      combination of FS_READABLE, FS_WRITABLE,  and  FS_EXCEPTION.
  145.      As  well  as  setting  this  select  state after each client
  146.      operation, it may be set asynchronously with the  Pdev_Ready
  147.      procedure.
  148.  
  149. PPDDEEVV__CCLLOOSSEE
  150.           ReturnStatus
  151.           CloseProc(private)
  152.               ClientData private;  /* Set by openProc */
  153.      This is called when the client  closes  its  stream  to  the
  154.      pseudo-device.   Dups  and  forks  are  not  visible  to the
  155.      pseudo-device server, so the CloseProc is only  called  once
  156.      when the stream to the pseudo-device is really going away.
  157.  
  158. PPDDEEVV__RREEAADD
  159.           ReturnStatus
  160.           ReadProc(private, offset, familyID, numBytesPtr, bufferPtr, freeItPtr, selectBitsPtr)
  161.               ClientData private;  /* Set by openProc */
  162.               int offset;          /* Byte offset at which to read */
  163.               int *numBytesPtr;    /* In/Out - num bytes to read/were read */
  164.               Address *bufferPtr;  /* Pointer to Buffer to hold data.  This
  165.                           * can be re-allocated by ReadProc. */
  166.               Boolean *freeItPtr;  /* TRUE if *bufferPtr is dynamically allocated. */
  167.               int *selectBitsPtr;  /* Return - select state of the pseudo-device */
  168.  
  169.      The read service procedure is passed a pointer to  a  buffer
  170.      which  it  should  fill  with  data  in order to satisfy the
  171.      client's read  request.   The  read  service  procedure  can
  172.      either  use the preallocated buffer, or change the buffer to
  173.      one of its own choosing.  The freeItPtr parameter  indicates
  174.      if  the buffer is dynamically allocated.  The library uses a
  175.      buffer on the stack which is FS_BLOCK_SIZE bytes  long,  but
  176.      will  dynamically  allocate a new one if the read request is
  177.      for more bytes than this.  If the service procedure  changes
  178.      the  buffer it should free the passed in buffer if indicated
  179.      by *freeItPtr, and it should set *freeItPtr appropriately so
  180.      the  library  can  free  the  buffer  after  completing  the
  181.      PDEV_READ transaction  with  the  kernel.   The  numBytesPtr
  182.      indicates  how  much  data  is  requested,  and it should be
  183.      updated to reflect the amount of data actually returned.
  184.  
  185. PPDDEEVV__WWRRIITTEE
  186.           ReturnStatus
  187.           WriteProc(private, offset, familyID, numBytesPtr, buffer, selectBitsPtr)
  188.               ClientData private;  /* Set by openProc */
  189.               int offset;          /* Byte offset at which to write */
  190.               int *numBytesPtr;    /* In/Out - num bytes to write/were written */
  191.               Address buffer; /* Buffer that holds data written by client */
  192.               int *selectBitsPtr;  /* Return - select state of the pseudo-device */
  193.  
  194.  
  195.  
  196.  
  197. Sprite v.1.0       Printed:  January 19, 1989                   3
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204. Pdev_Open          UNKNOWN SECTION (libcalls)           Pdev_Open
  205.  
  206.  
  207.  
  208.      The write service procedure is passed  a  buffer  containing
  209.      the  data  written  by the client.  The numBytesPtr argument
  210.      should be updated to reflect how much data was processed  by
  211.      the service procedure.
  212.  
  213. PPDDEEVV__IIOOCCTTLL
  214.           ReturnStatus
  215.           IoctlProc(private, command, familyID, byteOrder, inSize, inBuffer, outSizePtr,
  216.                outBuffer, selectBitsPtr)
  217.               ClientData private;  /*Set by open service procedure*/
  218.               int command;    /*IOControl command*/
  219.               int familyID;   /*Family ID of calling process*/
  220.               int byteOrder;  /*Indicates clients byte ordering */
  221.               int inSize;          /*Size of inBuffer*/
  222.               Address inBuffer;    /*Buffer containing input data*/
  223.               int *outSizePtr;     /*Resutl - size of outBuffer*/
  224.               Address outBuffer;   /*Buffer containing result data*/
  225.               int *selectBitsPtr;  /*Return - select state of pdev*/
  226.  
  227.      The ioctl service procedure involves two buffers,  one  con-
  228.      taining input data, and one for data returned to the client.
  229.      The ioctlProc has to set *outSizePtr to  indicate  how  much
  230.      data  is being returned to the client process.  This data is
  231.      not byteswapped by the operating system in the case that the
  232.      client  is  on  a  host  with  different byte-ordering.  The
  233.      client's byte order is indicated by the byteOrder  argument,
  234.      and  the  SSwwaapp__BBuuffffeerr  library  routine  can be used to swap
  235.      incomming and outgoing buffers.
  236.  
  237. SSEEEE AALLSSOO
  238.      Pdev_Ready, Pdev_Close, Pfs_Open, Swap_Buffer
  239.  
  240. KKEEYYWWOORRDDSS
  241.      pseudo-device
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263. Sprite v.1.0       Printed:  January 19, 1989                   4
  264.  
  265.  
  266.  
  267.